/*
 * $Id: HibernateOperations.java
 * Created on 2004-12-29 13:37:08
 */
package cn.donave.framework.hibernate;

import java.io.Serializable;
import java.sql.Connection;
import java.util.Collection;
import java.util.Iterator;
import java.util.List;

import org.hibernate.LockMode;
import org.hibernate.Query;
import org.hibernate.SQLQuery;
import org.hibernate.metadata.ClassMetadata;
import org.hibernate.type.Type;

import cn.donave.framework.exception.DoNaveException;

/**
 * 
 * @author Tim Du
 * @version $Revision: 2.0
 */
@SuppressWarnings("unchecked")
public interface HibernateOperations {

	/**
	 * Return the persistent instance of the given entity class with the given
	 * identifier, or null if not found.
	 * 
	 * @param entityClass
	 *            a persistent class
	 * @param id
	 *            an identifier of the persistent instance
	 * @return the persistent instance, or null if not found
	 * @throws com.DoNaveException.framework.DataAccessException
	 *             in case of Hibernate errors
	 * @see net.sf.hibernate.Session#get(Class, java.io.Serializable)
	 */

	Object get(Class entityClass, Serializable id) throws DoNaveException;

	/**
	 * Return the persistent instance of the given entity class with the given
	 * identifier, throwing an exception if not found.
	 * 
	 * @param entityClass
	 *            a persistent class
	 * @param id
	 *            an identifier of the persistent instance
	 * @return the persistent instance
	 * @throws HibernateObjectRetrievalFailureException
	 *             if the instance could not be found
	 * @throws com.DoNaveException.framework.DataAccessException
	 *             in case of Hibernate errors
	 * @see net.sf.hibernate.Session#load(Class, java.io.Serializable)
	 */
	Object load(Class entityClass, Serializable id) throws DoNaveException;

	/**
	 * Return all persistent instances of the given entity class. Note: Use
	 * queries or criteria for retrieving a specific subset.
	 * 
	 * @param entityClass
	 *            a persistent class
	 * @return a List containing 0 or more persistent instances
	 * @throws com.DoNaveException.framework.DataAccessException
	 *             if there is a Hibernate error
	 * @see net.sf.hibernate.Session#createCriteria
	 */
	List loadAll(Class entityClass) throws DoNaveException;

	/**
	 * Load the persistent instance with the given identifier into the given
	 * object, throwing an exception if not found.
	 * 
	 * @param entity
	 *            the object (of the target class) to load into
	 * @param id
	 *            an identifier of the persistent instance
	 * @throws HibernateObjectRetrievalFailureException
	 *             if the instance could not be found
	 * @throws com.DoNaveException.framework.DataAccessException
	 *             in case of Hibernate errors
	 * @see net.sf.hibernate.Session#load(Object, java.io.Serializable)
	 */
	void load(Object entity, Serializable id) throws DoNaveException;

	/**
	 * Re-read the state of the given persistent instance.
	 * 
	 * @param entity
	 *            the persistent instance to re-read
	 * @throws com.DoNaveException.framework.DataAccessException
	 *             in case of Hibernate errors
	 * @see net.sf.hibernate.Session#refresh(Object)
	 */
	void refresh(Object entity) throws DoNaveException;

	/**
	 * Check whether the given object is in the Session cache.
	 * 
	 * @param entity
	 *            the persistence instance to check
	 * @return whether the given object is in the Session cache
	 * @throws com.DoNaveException.framework.DataAccessException
	 *             if there is a Hibernate error
	 * @see net.sf.hibernate.Session#contains
	 */
	boolean contains(Object entity) throws DoNaveException;

	/**
	 * Remove the given object from the Session cache.
	 * 
	 * @param entity
	 *            the persistent instance to evict
	 * @throws com.DoNaveException.framework.DataAccessException
	 *             in case of Hibernate errors
	 * @see net.sf.hibernate.Session#evict
	 */
	void evict(Object entity) throws DoNaveException;

	/**
	 * Force initialization of a Hibernate proxy or persistent collection.
	 * 
	 * @param proxy
	 *            a proxy for a persistent object or a persistent collection
	 * @throws DoNaveException
	 *             if we can't initialize the proxy, for example because it is
	 *             not associated with an active Session
	 * @see net.sf.hibernate.Hibernate#initialize
	 */
	void initialize(Object proxy) throws DoNaveException;

	// -------------------------------------------------------------------------
	// Convenience methods for storing individual objects
	// -------------------------------------------------------------------------

	/**
	 * Persist the given transient instance.
	 * 
	 * @param entity
	 *            the transient instance to persist
	 * @return the generated identifier
	 * @throws com.DoNaveException.framework.DataAccessException
	 *             in case of Hibernate errors
	 * @see net.sf.hibernate.Session#save(Object)
	 */
	Serializable save(Object entity) throws DoNaveException;

	/**
	 * Save respectively update the given persistent instance, according to its
	 * ID (matching the configured "unsaved-value"?).
	 * 
	 * @param entity
	 *            the persistent instance to save respectively update (to be
	 *            associated with the Hibernate Session)
	 * @throws DoNaveException
	 *             in case of Hibernate errors
	 * @see net.sf.hibernate.Session#saveOrUpdate(Object)
	 */
	void saveOrUpdate(Object entity) throws DoNaveException;

	/**
	 * Save respectively update the contents of given persistent object,
	 * according to its ID (matching the configured "unsaved-value"?). Will copy
	 * the contained fields to an already loaded instance with the same ID, if
	 * appropriate.
	 * 
	 * @param entity
	 *            the persistent object to save respectively update ( <i>not
	 *            </i> necessarily to be associated with the Hibernate Session)
	 * @return the actually associated persistent object (either an already
	 *         loaded instance with the same ID, or the given object)
	 * @throws DoNaveException
	 *             in case of Hibernate errors
	 * @see net.sf.hibernate.Session#saveOrUpdateCopy(Object)
	 */
	Object saveOrUpdateCopy(Object entity) throws DoNaveException;

	/**
	 * Update the given persistent instance.
	 * 
	 * @param entity
	 *            the persistent instance to update
	 * @throws com.DoNaveException.framework.DataAccessException
	 *             in case of Hibernate errors
	 * @see net.sf.hibernate.Session#update(Object)
	 */
	void update(Object entity) throws DoNaveException;

	/**
	 * Delete the given persistent instance.
	 * 
	 * @param entity
	 *            the persistent instance to delete
	 * @throws com.DoNaveException.framework.DataAccessException
	 *             in case of Hibernate errors
	 * @see net.sf.hibernate.Session#delete(Object)
	 */
	void delete(Object entity) throws DoNaveException;

	/**
	 * Delete all given persistent instances.
	 * <p>
	 * This can be combined with any of the find methods to delete by query in
	 * two lines of code, similar to Session's delete by query methods.
	 * 
	 * @param entities
	 *            the persistent instances to delete
	 * @throws com.DoNaveException.framework.DataAccessException
	 *             in case of Hibernate errors
	 * @see net.sf.hibernate.Session#delete(String)
	 */
	void deleteAll(Collection entities) throws DoNaveException;

	/**
	 * Flush all pending saves, updates and deletes to the database.
	 * <p>
	 * Only invoke this for selective eager flushing, for example when JDBC code
	 * needs to see certain changes within the same transaction. Else, it's
	 * preferable to rely on auto-flushing at transaction completion.
	 * 
	 * @throws com.DoNaveException.framework.DataAccessException
	 *             in case of Hibernate errors
	 * @see net.sf.hibernate.Session#flush
	 */
	void flush() throws DoNaveException;

	/**
	 * Remove all objects from the Session cache, and cancel all pending saves,
	 * updates and deletes.
	 * 
	 * @throws com.DoNaveException.framework.DataAccessException
	 *             in case of Hibernate errors
	 * @see net.sf.hibernate.Session#clear
	 */
	void clear() throws DoNaveException;

	// -------------------------------------------------------------------------
	// Convenience finder methods for HQL strings
	// -------------------------------------------------------------------------

	/**
	 * Execute a query for persistent instances.
	 * 
	 * @param queryString
	 *            a query expressed in Hibernate's query language
	 * @return a List containing 0 or more persistent instances
	 * @throws com.DoNaveException.framework.DataAccessException
	 *             in case of Hibernate errors
	 * @see net.sf.hibernate.Session#find(String)
	 * @see net.sf.hibernate.Session#createQuery
	 */
	List find(String queryString) throws DoNaveException;

	/**
	 * Execute a query for persistent instances, binding one value to a "?"
	 * parameter in the query string.
	 * 
	 * @param queryString
	 *            a query expressed in Hibernate's query language
	 * @param value
	 *            the value of the parameter
	 * @return a List containing 0 or more persistent instances
	 * @throws com.DoNaveException.framework.DataAccessException
	 *             in case of Hibernate errors
	 * @see net.sf.hibernate.Session#find(String, Object,
	 *      net.sf.hibernate.type.Type)
	 * @see net.sf.hibernate.Session#createQuery
	 */
	List find(String queryString, Object value) throws DoNaveException;

	List find(String queryString, String name, Object value)
			throws DoNaveException;

	/**
	 * Execute a query for persistent instances, binding one value to a "?"
	 * parameter of the given type in the query string.
	 * 
	 * @param queryString
	 *            a query expressed in Hibernate's query language
	 * @param value
	 *            the value of the parameter
	 * @param type
	 *            Hibernate type of the parameter (or null)
	 * @return a List containing 0 or more persistent instances
	 * @throws com.DoNaveException.framework.DataAccessException
	 *             in case of Hibernate errors
	 * @see net.sf.hibernate.Session#find(String, Object,
	 *      net.sf.hibernate.type.Type)
	 * @see net.sf.hibernate.Session#createQuery
	 */
	List find(String queryString, Object value, Type type)
			throws DoNaveException;

	List find(String queryString, String name, Object value, Type type)
			throws DoNaveException;

	/**
	 * Execute a query for persistent instances, binding a number of values to
	 * "?" parameters in the query string.
	 * 
	 * @param queryString
	 *            a query expressed in Hibernate's query language
	 * @param values
	 *            the values of the parameters
	 * @return a List containing 0 or more persistent instances
	 * @throws com.DoNaveException.framework.DataAccessException
	 *             in case of Hibernate errors
	 * @see net.sf.hibernate.Session#find(String, Object[],
	 *      net.sf.hibernate.type.Type[])
	 * @see net.sf.hibernate.Session#createQuery
	 */
	List find(String queryString, Object[] values) throws DoNaveException;

	List find(String queryString, String[] names, Object[] values)
			throws DoNaveException;

	/**
	 * Execute a query for persistent instances, binding a number of values to
	 * "?" parameters of the given types in the query string.
	 * 
	 * @param queryString
	 *            a query expressed in Hibernate's query language
	 * @param values
	 *            the values of the parameters
	 * @param types
	 *            Hibernate types of the parameters (or null)
	 * @return a List containing 0 or more persistent instances
	 * @throws com.DoNaveException.framework.DataAccessException
	 *             in case of Hibernate errors
	 * @see net.sf.hibernate.Session#find(String, Object[],
	 *      net.sf.hibernate.type.Type[])
	 * @see net.sf.hibernate.Session#createQuery
	 */
	List find(String queryString, Object[] values, Type[] types)
			throws DoNaveException;

	List find(String queryString, String[] names, Object[] values, Type[] types)
			throws DoNaveException;

	/**
	 * Execute a query for persistent instances, binding one value to a ":"
	 * named parameter in the query string.
	 * 
	 * @param queryString
	 *            the name of a Hibernate query in a mapping file
	 * @param paramName
	 *            the name of parameter
	 * @param value
	 *            the value of the parameter
	 * @return a List containing 0 or more persistent instances
	 * @throws com.DoNaveException.framework.DataAccessException
	 *             in case of Hibernate errors
	 * @see net.sf.hibernate.Session#find(String, Object,
	 *      net.sf.hibernate.type.Type)
	 * @see net.sf.hibernate.Session#getNamedQuery(String)
	 */
	List findByNamedParam(String queryString, String paramName, Object value)
			throws DoNaveException;

	/**
	 * Execute a query for persistent instances, binding one value to a ":"
	 * named parameter in the query string.
	 * 
	 * @param queryString
	 *            the name of a Hibernate query in a mapping file
	 * @param paramName
	 *            the name of the parameter
	 * @param value
	 *            the value of the parameter
	 * @param type
	 *            Hibernate type of the parameter (or null)
	 * @return a List containing 0 or more persistent instances
	 * @throws com.DoNaveException.framework.DataAccessException
	 *             in case of Hibernate errors
	 * @see net.sf.hibernate.Session#find(String, Object,
	 *      net.sf.hibernate.type.Type)
	 * @see net.sf.hibernate.Session#getNamedQuery(String)
	 */
	List findByNamedParam(String queryString, String paramName, Object value,
			Type type) throws DoNaveException;

	/**
	 * Execute a query for persistent instances, binding a number of values to
	 * ":" named parameters in the query string.
	 * 
	 * @param queryString
	 *            a query expressed in Hibernate's query language
	 * @param paramNames
	 *            the names of the parameters
	 * @param values
	 *            the values of the parameters
	 * @return a List containing 0 or more persistent instances
	 * @throws com.DoNaveException.framework.DataAccessException
	 *             in case of Hibernate errors
	 * @see net.sf.hibernate.Session#find(String, Object[],
	 *      net.sf.hibernate.type.Type[])
	 * @see net.sf.hibernate.Session#getNamedQuery(String)
	 */
	List findByNamedParam(String queryString, String[] paramNames,
			Object[] values) throws DoNaveException;

	/**
	 * Execute a query for persistent instances, binding a number of values to
	 * ":" named parameters in the query string.
	 * 
	 * @param queryString
	 *            a query expressed in Hibernate's query language
	 * @param paramNames
	 *            the names of the parameters
	 * @param values
	 *            the values of the parameters
	 * @param types
	 *            Hibernate types of the parameters (or null)
	 * @return a List containing 0 or more persistent instances
	 * @throws com.DoNaveException.framework.DataAccessException
	 *             in case of Hibernate errors
	 * @see net.sf.hibernate.Session#find(String, Object[],
	 *      net.sf.hibernate.type.Type[])
	 * @see net.sf.hibernate.Session#getNamedQuery(String)
	 */
	List findByNamedParam(String queryString, String[] paramNames,
			Object[] values, Type[] types) throws DoNaveException;

	/**
	 * Execute a query for persistent instances, binding the properties of the
	 * given bean to <i>named </i> parameters in the query string.
	 * 
	 * @param queryString
	 *            a query expressed in Hibernate's query language
	 * @param valueBean
	 *            the values of the parameters
	 * @return a List containing 0 or more persistent instances
	 * @throws com.DoNaveException.framework.DataAccessException
	 *             in case of Hibernate errors
	 * @see net.sf.hibernate.Query#setProperties
	 * @see net.sf.hibernate.Session#createQuery
	 */
	List findByValueBean(String queryString, Object valueBean)
			throws DoNaveException;

	// -------------------------------------------------------------------------
	// Convenience finder methods for named queries
	// -------------------------------------------------------------------------

	/**
	 * Execute a named query for persistent instances. A named query is defined
	 * in a Hibernate mapping file.
	 * 
	 * @param queryName
	 *            the name of a Hibernate query in a mapping file
	 * @return a List containing 0 or more persistent instances
	 * @throws com.DoNaveException.framework.DataAccessException
	 *             in case of Hibernate errors
	 * @see net.sf.hibernate.Session#find(String)
	 * @see net.sf.hibernate.Session#getNamedQuery(String)
	 */
	List findByNamedQuery(String queryName) throws DoNaveException;

	/**
	 * Execute a named query for persistent instances, binding one value to a
	 * "?" parameter in the query string. A named query is defined in a
	 * Hibernate mapping file.
	 * 
	 * @param queryName
	 *            the name of a Hibernate query in a mapping file
	 * @return a List containing 0 or more persistent instances
	 * @throws com.DoNaveException.framework.DataAccessException
	 *             in case of Hibernate errors
	 * @see net.sf.hibernate.Session#find(String, Object,
	 *      net.sf.hibernate.type.Type)
	 * @see net.sf.hibernate.Session#getNamedQuery(String)
	 */
	List findByNamedQuery(String queryName, Object value)
			throws DoNaveException;

	/**
	 * Execute a named query for persistent instances, binding one value to a
	 * "?" parameter in the query string. A named query is defined in a
	 * Hibernate mapping file.
	 * 
	 * @param queryName
	 *            the name of a Hibernate query in a mapping file
	 * @param type
	 *            Hibernate type of the parameter (or null)
	 * @return a List containing 0 or more persistent instances
	 * @throws com.DoNaveException.framework.DataAccessException
	 *             in case of Hibernate errors
	 * @see net.sf.hibernate.Session#find(String, Object,
	 *      net.sf.hibernate.type.Type)
	 * @see net.sf.hibernate.Session#getNamedQuery(String)
	 */
	List findByNamedQuery(String queryName, Object value, Type type)
			throws DoNaveException;

	/**
	 * Execute a named query for persistent instances, binding a number of
	 * values to "?" parameters in the query string. A named query is defined in
	 * a Hibernate mapping file.
	 * 
	 * @param queryName
	 *            the name of a Hibernate query in a mapping file
	 * @param values
	 *            the values of the parameters
	 * @return a List containing 0 or more persistent instances
	 * @throws com.DoNaveException.framework.DataAccessException
	 *             in case of Hibernate errors
	 * @see net.sf.hibernate.Session#find(String, Object[],
	 *      net.sf.hibernate.type.Type[])
	 * @see net.sf.hibernate.Session#getNamedQuery(String)
	 */
	List findByNamedQuery(String queryName, Object[] values)
			throws DoNaveException;

	/**
	 * Execute a named query for persistent instances, binding a number of
	 * values to "?" parameters in the query string. A named query is defined in
	 * a Hibernate mapping file.
	 * 
	 * @param queryName
	 *            the name of a Hibernate query in a mapping file
	 * @param values
	 *            the values of the parameters
	 * @param types
	 *            Hibernate types of the parameters (or null)
	 * @return a List containing 0 or more persistent instances
	 * @throws com.DoNaveException.framework.DataAccessException
	 *             in case of Hibernate errors
	 * @see net.sf.hibernate.Session#find(String, Object[],
	 *      net.sf.hibernate.type.Type[])
	 * @see net.sf.hibernate.Session#getNamedQuery(String)
	 */
	List findByNamedQuery(String queryName, Object[] values, Type[] types)
			throws DoNaveException;

	/**
	 * Execute a named query for persistent instances, binding one value to a
	 * ":" named parameter in the query string. A named query is defined in a
	 * Hibernate mapping file.
	 * 
	 * @param queryName
	 *            the name of a Hibernate query in a mapping file
	 * @param paramName
	 *            the name of parameter
	 * @param value
	 *            the value of the parameter
	 * @return a List containing 0 or more persistent instances
	 * @throws com.DoNaveException.framework.DataAccessException
	 *             in case of Hibernate errors
	 * @see net.sf.hibernate.Session#find(String, Object,
	 *      net.sf.hibernate.type.Type)
	 * @see net.sf.hibernate.Session#getNamedQuery(String)
	 */
	List findByNamedQueryAndNamedParam(String queryName, String paramName,
			Object value) throws DoNaveException;

	/**
	 * Execute a named query for persistent instances, binding one value to a
	 * ":" named parameter in the query string. A named query is defined in a
	 * Hibernate mapping file.
	 * 
	 * @param queryName
	 *            the name of a Hibernate query in a mapping file
	 * @param paramName
	 *            the name of the parameter
	 * @param value
	 *            the value of the parameter
	 * @param type
	 *            Hibernate type of the parameter (or null)
	 * @return a List containing 0 or more persistent instances
	 * @throws com.DoNaveException.framework.DataAccessException
	 *             in case of Hibernate errors
	 * @see net.sf.hibernate.Session#find(String, Object,
	 *      net.sf.hibernate.type.Type)
	 * @see net.sf.hibernate.Session#getNamedQuery(String)
	 */
	List findByNamedQueryAndNamedParam(String queryName, String paramName,
			Object value, Type type) throws DoNaveException;

	/**
	 * Execute a named query for persistent instances, binding a number of
	 * values to ":" named parameters in the query string. A named query is
	 * defined in a Hibernate mapping file.
	 * 
	 * @param queryName
	 *            the name of a Hibernate query in a mapping file
	 * @param paramNames
	 *            the names of the parameters
	 * @param values
	 *            the values of the parameters
	 * @return a List containing 0 or more persistent instances
	 * @throws com.DoNaveException.framework.DataAccessException
	 *             in case of Hibernate errors
	 * @see net.sf.hibernate.Session#find(String, Object[],
	 *      net.sf.hibernate.type.Type[])
	 * @see net.sf.hibernate.Session#getNamedQuery(String)
	 */
	List findByNamedQueryAndNamedParam(String queryName, String[] paramNames,
			Object[] values) throws DoNaveException;

	/**
	 * Execute a named query for persistent instances, binding a number of
	 * values to ":" named parameters in the query string. A named query is
	 * defined in a Hibernate mapping file.
	 * 
	 * @param queryName
	 *            the name of a Hibernate query in a mapping file
	 * @param paramNames
	 *            the names of the parameters
	 * @param values
	 *            the values of the parameters
	 * @param types
	 *            Hibernate types of the parameters (or null)
	 * @return a List containing 0 or more persistent instances
	 * @throws com.DoNaveException.framework.DataAccessException
	 *             in case of Hibernate errors
	 * @see net.sf.hibernate.Session#find(String, Object[],
	 *      net.sf.hibernate.type.Type[])
	 * @see net.sf.hibernate.Session#getNamedQuery(String)
	 */
	List findByNamedQueryAndNamedParam(String queryName, String[] paramNames,
			Object[] values, Type[] types) throws DoNaveException;

	/**
	 * Execute a named query for persistent instances, binding the properties of
	 * the given bean to ":" named parameters in the query string. A named query
	 * is defined in a Hibernate mapping file.
	 * 
	 * @param queryName
	 *            the name of a Hibernate query in a mapping file
	 * @param valueBean
	 *            the values of the parameters
	 * @return a List containing 0 or more persistent instances
	 * @throws com.DoNaveException.framework.DataAccessException
	 *             in case of Hibernate errors
	 * @see net.sf.hibernate.Query#setProperties
	 * @see net.sf.hibernate.Session#getNamedQuery(String)
	 */
	List findByNamedQueryAndValueBean(String queryName, Object valueBean)
			throws DoNaveException;

	// -------------------------------------------------------------------------
	// Convenience query methods for iterate and delete
	// -------------------------------------------------------------------------

	/**
	 * Execute a query for persistent instances.
	 * <p>
	 * Returns the results as Iterator. Entities returned are initialized on
	 * demand. See Hibernate docs for details.
	 * 
	 * @param queryString
	 *            a query expressed in Hibernate's query language
	 * @return a List containing 0 or more persistent instances
	 * @throws com.DoNaveException.framework.DataAccessException
	 *             in case of Hibernate errors
	 * @see net.sf.hibernate.Session#iterate(String)
	 * @see net.sf.hibernate.Session#createQuery
	 */
	Iterator iterate(String queryString) throws DoNaveException;

	/**
	 * Execute a query for persistent instances, binding one value to a "?"
	 * parameter in the query string.
	 * <p>
	 * Returns the results as Iterator. Entities returned are initialized on
	 * demand. See Hibernate docs for details.
	 * 
	 * @param queryString
	 *            a query expressed in Hibernate's query language
	 * @param value
	 *            the value of the parameter
	 * @return a List containing 0 or more persistent instances
	 * @throws com.DoNaveException.framework.DataAccessException
	 *             in case of Hibernate errors
	 * @see net.sf.hibernate.Session#iterate(String, Object,
	 *      net.sf.hibernate.type.Type)
	 * @see net.sf.hibernate.Session#createQuery
	 */
	Iterator iterate(String queryString, Object value)
			throws DoNaveException;

	/**
	 * Execute a query for persistent instances, binding one value to a "?"
	 * parameter of the given type in the query string.
	 * <p>
	 * Returns the results as Iterator. Entities returned are initialized on
	 * demand. See Hibernate docs for details.
	 * 
	 * @param queryString
	 *            a query expressed in Hibernate's query language
	 * @param value
	 *            the value of the parameter
	 * @param type
	 *            Hibernate type of the parameter (or null)
	 * @return a List containing 0 or more persistent instances
	 * @throws com.DoNaveException.framework.DataAccessException
	 *             in case of Hibernate errors
	 * @see net.sf.hibernate.Session#iterate(String, Object,
	 *      net.sf.hibernate.type.Type)
	 * @see net.sf.hibernate.Session#createQuery
	 */
	Iterator iterate(String queryString, Object value, Type type)
			throws DoNaveException;

	/**
	 * Execute a query for persistent instances, binding a number of values to
	 * "?" parameters in the query string.
	 * <p>
	 * Returns the results as Iterator. Entities returned are initialized on
	 * demand. See Hibernate docs for details.
	 * 
	 * @param queryString
	 *            a query expressed in Hibernate's query language
	 * @param values
	 *            the values of the parameters
	 * @return a List containing 0 or more persistent instances
	 * @throws com.DoNaveException.framework.DataAccessException
	 *             in case of Hibernate errors
	 * @see net.sf.hibernate.Session#find(String, Object[],
	 *      net.sf.hibernate.type.Type[])
	 * @see net.sf.hibernate.Session#createQuery
	 */
	Iterator iterate(String queryString, Object[] values)
			throws DoNaveException;

	/**
	 * Execute a query for persistent instances, binding a number of values to
	 * "?" parameters of the given types in the query string.
	 * <p>
	 * Returns the results as Iterator. Entities returned are initialized on
	 * demand. See Hibernate docs for details.
	 * 
	 * @param queryString
	 *            a query expressed in Hibernate's query language
	 * @param values
	 *            the values of the parameters
	 * @param types
	 *            Hibernate types of the parameters (or null)
	 * @return a List containing 0 or more persistent instances
	 * @throws com.DoNaveException.framework.DataAccessException
	 *             in case of Hibernate errors
	 * @see net.sf.hibernate.Session#find(String, Object[],
	 *      net.sf.hibernate.type.Type[])
	 * @see net.sf.hibernate.Session#createQuery
	 */
	Iterator iterate(String queryString, Object[] values, Type[] types)
			throws DoNaveException;

	/**
	 * Close an Iterator created by <i>iterate </i> operations immediately,
	 * instead of waiting until the session is closed or disconnected.
	 * 
	 * @param it
	 *            the Iterator to close
	 * @throws DoNaveException
	 *             if the Iterator could not be closed
	 * @see net.sf.hibernate.Hibernate#close
	 */
	void closeIterator(Iterator it) throws DoNaveException;

	/**
	 * Delete all objects returned by the query. Return the number of objects
	 * deleted.
	 * 
	 * @param queryString
	 *            a query expressed in Hibernate's query language
	 * @return the number of instances deleted
	 * @throws com.DoNaveException.framework.DataAccessException
	 *             in case of Hibernate errors
	 * @see net.sf.hibernate.Session#delete(String)
	 */
	int delete(String queryString) throws DoNaveException;

	/**
	 * Delete all objects returned by the query. Return the number of objects
	 * deleted.
	 * 
	 * @param queryString
	 *            a query expressed in Hibernate's query language
	 * @param value
	 *            the value of the parameter
	 * @param type
	 *            Hibernate type of the parameter (or null)
	 * @return the number of instances deleted
	 * @throws com.DoNaveException.framework.DataAccessException
	 *             in case of Hibernate errors
	 * @see net.sf.hibernate.Session#delete(String, Object,
	 *      net.sf.hibernate.type.Type)
	 */
	int delete(String queryString, Object value, Type type)
			throws DoNaveException;

	/**
	 * Delete all objects returned by the query. Return the number of objects
	 * deleted.
	 * 
	 * @param queryString
	 *            a query expressed in Hibernate's query language
	 * @param values
	 *            the values of the parameters
	 * @param types
	 *            Hibernate types of the parameters (or null)
	 * @return the number of instances deleted
	 * @throws com.DoNaveException.framework.DataAccessException
	 *             in case of Hibernate errors
	 * @see net.sf.hibernate.Session#delete(String, Object[],
	 *      net.sf.hibernate.type.Type[])
	 */
	int delete(String queryString, Object[] values, Type[] types)
			throws DoNaveException;

	void doGetTransaction() throws DoNaveException;

	void doCommit() throws DoNaveException;

	void doRollback() throws DoNaveException;

	void closeSession() throws DoNaveException;

	Query createQuery(String queryName) throws DoNaveException;

	SQLQuery createSQLQuery(String sqlQuery, String aliasName, Class clazz)
			throws DoNaveException;

	ClassMetadata getMetadata(Class clazz) throws DoNaveException;

	Connection getConnection() throws DoNaveException;
}